SuperHack/SuperHack CD.bin/CODING/GRAPHICS/13HLIB.ZIP/13HLIB.DOX

Text File | 1996-08-10 | 15.9 KB | 394 lines

User's Manual for Mode13hLib                 Coded by Pri$m
────────────────────────────                 ──────────────

Contents
────────

  Note from the Author

1 Notes on the usage of Mode13hLib
·    Error checking
·    Sprites
·    Page Flipping
·    The Flip Page and out of bounds Sprites.

2 Structures and typedefs
·    ColorStruct
·    Sprite

3 Member Functions
·    SetMode13h
·    CloseMode13h
·    DetectVGA
·    ClearScreen
·    PlotPixel
·    GetPixel
·    GetPaletteColor
·    SetPaletteColor
·    WaitVerticalRetrace
·    LoadPCXFile
·    LoadPalette
·    SavePalette
·    HorizontalLine
·    VerticalLine
·    Bar
·    Rectangle
·    GetSprite
·    DrawSprite
·    DrawSpriteNoTrans
·    WriteSpriteToDisk
·    ReadSpriteFromDisk
·    SetUpPage
·    ClosePage
·    PageActive
·    CopyPageToScreen
·    BltText
·    Line

4 Example programs
·    Palette Demo
·    Sprite Demo

5 Special notes on using page flipping
6 Greetings to ...


«────────────────────────────────────────────────────────────────────────────»

Note from the Author
────────────────────

Greetings!
──────────

Mode13hLib is an easy to use, fast graphics library that  (yeah, you guessed
it!) operates in Mode 13h. (19 in decimal) This library is primarily for
those who want to break free from the restrictions of BGI (slow, bulky, only
16 colors...) and enter the world of fast, 256 color graphics, without going
to the often impractical (especially for the hobby programmer) lengths of
writing their own library. The source code is also there to be disected
should you want to; feel free to rip code from it should you need to.

Mode13hLib is constructed in an object-oriented way, so that the complexity
of many of the functions is hidden from the user. It also becomes very easy
to conceptualise - all the functions belong to one, discreet object, they are
not just scattered around. Also, this means that if you would like to add on
to the library, you can easily derive a class from it and add your own
functions and variables to it.

Mode13hLib is FreeWare. That means you can give it to all your friends,
upload it to all the BBSs you like, and use it in any program you like.
That's what I wrote it for. There are, however, two conditions. The first is
that you do not remove my name and copyright from the code. It is not
visible to the user, but is hidden inside the .exe file. Also, when you
release any programs you've written with Mode13hLib, send me a letter
(PO Box 2412, Bedfordview 2008, South Africa), or email me ([e-mail]
or [e-mail]) telling me a bit about it. Mention in the
documentation is optional, but would be kewl!

Above all, have phun, and remember, the only limit is your imagination!

Regards,
       Pri$m.

«────────────────────────────────────────────────────────────────────────────»

Notes on the usage of Mode13hLib
────────────────────────────────

·    Error checking.
All functions in Mode13hLib that obtain a Sprite allocate the memory for that
Sprite using farmalloc(). (If you don't know what a Sprite is yet, don't
worry, it's coming up) Make sure that you KillSprite them when finished with
them. E.g.: KillSprite(SpriteName); This should also be done when you want
to replace an already used Sprite.

(KillSprite is a macro, with KillSprite(x) defined as
farfree(x))

Also, those function return values to indicate either SUCCESS or FAILURE.
Please check these values. The functions (especially for Sprites) that are
speed-critical do NOT check if you pass them a NULL pointer. HorizontalLine
does NOT check if you happen to pass it a negative argument. Please be
careful in this regard, as the results may be unpredictable. I have tried
using Bar() with a negative value, and it crashed my program.
Please be careful with this.

·    Sprites
Sprites are bitmapped images that are usually moved around the screen at a
rapid pace. They could be a spaceman (as in the example) or a ball. They are
to be used using the Sprite data type. There are two ways to draw a Sprite :
With transparent pixels, and without. Transparent pixels are pixels with a
value of 0. They are, therefore, not drawn on the screen. This means that
although a Sprite is stored in a rectangle, it may be round, or have a hole
in the middle. Without transparent pixels, ALL of the pixels on the Sprite
are drawn to the screen. This tends to be slightly faster than using
transparent pixels, but shapes other than squares, which are on a background,
present a problem. As an example of this, if the Spaceman was drawn using
no transparent pixels, the stars close to him, that you can see in the demo,
for instance right next to his helmet, would not be visible.

·    Page flipping
You may have noticed that sometimes when drawing on the screen, the image
flickers. This often happens when doing a lot of drawing. One solution to
this problem is WaitVerticalRetrace, which waits until Vertical Retrace (the
period when your monitor is not refreshing the screen) is occurring. Another
method goes hand in hand with WaitVerticalRetrace : Instead of drawing to the
screen, why not draw everything to a copy of the screen in memory, and then
copy it all across to the screen in one shot, saving time and flicker.
When you enable this option, all drawing is done to this copy. You must call
the function CopyPageToScreen to copy your image to the screen. The penalty
for this is that the amount of memory required to store an entire screen's
worth of pixels is about 64K. I left the choice up to you.

The Flip Page and out of bounds Sprites.
───────────────────────────────────────
Be extremely careful when drawing on the Flip Page. (Which will happen if you
say SetupPage()) If you draw a Sprite out of bounds, (off the page), memory
located in and around the flip page will become corrupted. DO NOT do this.
Experiments with it have caused my system to crash, or at best just bombed
out the program. Be careful and include error checking here. It's fine to
write over the side of the page, but not over the top or the bottom.

«────────────────────────────────────────────────────────────────────────────»

Structures and typedefs
───────────────────────
·    ColorStruct{
 unsigned char r;
 unsigned char g;
 unsigned char b;
};

ColorStruct is the structure defined for palette manipulation. It contains
three values, one for each of the three components of any color on the screen.
Each value can be only 0-63, otherwise it will be ignored if you try and
set the palette using it. (Each color pixel is made up of a certain
combination of these value. E.g. Dark Grey: r=3; b=63; g=63;, and Black: r=0;
g=0; b=0;)

·    typedef char far *Sprite;
  This typedef merely disguises the fact that a Sprite is stored as an array
of characters, (Almost the same way as a string [typedef unsigned char far*
Sprite]). All Sprite functions take this data type as arguments. When you
declare a Sprite, simply say "Sprite MySprite". To get a Sprite from a
function that returns a Sprite, just say:
"MySprite = Mode13h.ReadSpriteFromDisk("mysprite.m13");" Everything is coded
in this way, and this makes Sprite handling extremely easy. Just treat them
as any other data type.

«────────────────────────────────────────────────────────────────────────────»

Member Functions
────────────────

void SetMode13h()
─────────────────
Sets up VGA graphics mode 13h. (320x200x256)

void CloseMode13h()
───────────────────
Resets the monitor mode back to text mode.

int DetectVGA()
───────────────
Detects the presence of a VGA card on the system. Returns SUCCESS if there is
one, or FAILURE if there isn't.

void ClearScreen(unsigned char color)
─────────────────────────────────────
Clears the screen with the given color.

void PlotPixel(int x, int y, unsigned char color)
─────────────────────────────────────────────────
Places one pixel at x across, y down, with the given color.

unsigned char GetPixel(int x, int y)
────────────────────────────────────
Returns the color of the pixel at the specified location.

void GetPaletteColor(int index, ColorStruct& Colstr)
────────────────────────────────────────────────────
Places the information from the palette entry index into the ColorStruct
Colstr.

void SetPaletteColor(int index, ColorStruct &Colstr)
────────────────────────────────────────────────────
Copies the color information in Colstr into the palette entry specified by
index.

void WaitVerticalRetrace()
──────────────────────────
Waits until the monitor is in a Vertical Retrace period. This makes it easier
to draw to the screen without worrying about flicker. For flickerless drawing,
combine this with the use of a flip page. (Facilitates are provided for that -
see SetUpPage(). Call this before calling CopyPageToScreen() and you won't
ever have to worry about flicker.)

int LoadPCXFile(char *name)
───────────────────────────
Loads the PCX file specified by name to the screen. (Or swap page.) Returns
FAILURE if the PCX file could not be found or is not a Mode13h PCX file.
(320x200x256, 8 bits per pixel, etc. A good program to use for these is
Improces by John Wagner. (ShareWare)). Otherwise returns SUCCESS.

int LoadPalette(char *filename)
───────────────────────────────
Loads a palette from the given filename. If the file could not be opened,
returns FAILURE. Otherwise, returns SUCCESS. Note that this function is not
only able to read palette files from the function SavePalette, but also from
the ends of Mode13h PCX files.

int SavePalette(char *filename)
───────────────────────────────
Saves the current palette to the filename specified. If it could not open the
file, returns FAILURE, else returns SUCCESS.

void HorizontalLine(int x, int y, int xx, unsigned char color)
──────────────────────────────────────────────────────────────
Draws a horizontal line from x,y to xx,y in the specified color.

void VerticalLine(int x, int y, int yy, unsigned char color)
────────────────────────────────────────────────────────────
Draws a vertical line from x,y to x,yy in the given color.

void Bar(int x, int y, int width, int height, unsigned char color)
──────────────────────────────────────────────────────────────────
Draws a filled in rectangle in the color specified from x,y to x+width,
y+height.

void Rectangle(int x, int y, int width, int height, unsigned char color)
────────────────────────────────────────────────────────────────────────
Draw a rectangle is the specified color from x,y to x+width, y+height.

Sprite GetSprite(int x, int y, int width, int height)
─────────────────────────────────────────────────────
Gets a Sprite from the specified location with the specified width and height
and returns it.

void DrawSprite(int x, int y, int width, int height, Sprite Sprte)
──────────────────────────────────────────────────────────────────
Draws the given Sprite (Sprte) at the given co-ordinates on the screen, with
the given width and height. It ignores all pixels with value 0, thereby
making them `transparent'.

void DrawSpriteNoTrans(int x, int y, int width, int height, Sprite Sprte)
─────────────────────────────────────────────────────────────────────────
Draws the given Sprite (Sprte) in the same way as DrawSprite() except that it
does not ignore pixels with a value of 0. It is slightly faster than
DrawSprite().

int WriteSpriteToDisk(char *filename, int width, int height, Sprite Sprte)
──────────────────────────────────────────────────────────────────────────
Writes the specified Sprite to the specified file on disk. Returns FAILURE if
the Sprite could not be written, otherwise it returns SUCCESS. If the file
already exists, it is overwritten.

Sprite ReadSpriteFromDisk(char *filename)
─────────────────────────────────────────
Reads a Sprite from the specified file and returns it.

void SetUpPage()
────────────────
Sets up a swap page in memory. A swap page is like a `virtual screen', and
when you draw, it is drawn to. After that, you must call CopyPageToScreen()
to copy it to the actual screen. Using a swap page reduces flicker. (and with
WaitVerticalRetrace eliminates it) It does, however, use 64K of memory.

void ClosePage()
────────────────
Closes down the swap page. All drawing is now redirected to the screen. Do
this always before exiting a program that uses a swap page.

int PageActive()
────────────────
Returns whether or not the swap page is active. If it is, it returns SUCCESS,
otherwise it returns FAILURE. PageActive returning FAILURE after you have
called SetUpPage() (But not ClosePage()) indicates that the system did not
have enough memory for it.

void CopyPageToScreen()
───────────────────────
Copies the contents of the swap page to screen in one go.

Always call this if you are using a swap page and you want
what you drew displayed.

void BltText(char *text, int x, int y, unsigned char color)
───────────────────────────────────────────────────────────
Prints out the specified string at the given co-ordinates (x, y), in the
given color.

void Line(int x1, int y1, int x2, int y2, unsigned char color)
──────────────────────────────────────────────────────────────
Draws a line from x1,y1 to x2,y2 in the given color.

«────────────────────────────────────────────────────────────────────────────»

Example programs
────────────────
·    Palette Demo (paldemo.exe)
The Palette demo is a short demonstration of the effects that can be achieved
by simple manipulation of the palette. It uses a couple of loops to set the
palette colors into 64 shades of red, 64 shades of blue, 64 shades of green
and about 50 shades of grey. It then draws a couple of lines, in ascending
order of the palette, which are slowed down for visual effect. (Note that had
they not been slowed down, the drawing would be done instantly, with no
visual indication) It then draws on the extra shades of grey, and fades out.
(A nice little palette trick to accomplish a seemingly hard effect easily)

·    Sprite demo (sprdemo.exe)
The Sprite demo is another small demo I wrote to demonstrate the Sprite
handling capabilities of Mode13hLib. It draws a random series of stars, and
then `walks' a pre-saved animation of a spaceman up the screen. At the same
time it also bounces some text along the top of the screen. It took very few
lines of code to create a working, hi-speed (it needed a delay to look right)
demo.

«────────────────────────────────────────────────────────────────────────────»

Special Notes on Using Page Flipping.
────────────────────────────────────
Page Flipping is enabled by calling Mode13hLib.SetUpPage(). It can be
disabled by calling Mode13hLib.ClosePage(). Please always check that the page
you've tried to create was actually created. Do this by calling
Mode13hLib.PageActive(). The function will return SUCCESS if it is. FAILURE
means that the system did not have the 64K of memory needed for the swap page.
This is extremely important, because if after that you try and
CopyPageToScreen(), the results are definitely going to be messy.

«────────────────────────────────────────────────────────────────────────────»

Greetings to ...
────────────────
Greetings to the following:

The rest of The BRiGADE:
 - BLiTZ
 - MATRiX
 - MERLyN
 - HoTRod
 - HaRdRocK

- CD & SX
- Elquin   (Are we having fun yet ... ?!)
- JYnXx    << Black MagiK BBS ([phone]) >>
- ReVerB
- HACKERJACk
- Grystal
- Psycho Bunny
- Gumpf

- Special thanx to Amit J Patel, who runs a waaay kewl Games Programming Page
 at http://www-cs-students.stanford.edu/~amitp/gameprog.html, for help
 on finding a Line algorithm. His help was much appreciated!!

«────────────────────────────────────────────────────────────────────────────»
         "He rides the wild October sky;
          He shall not die;
          He shall not die."
 - The ScareCrows.
«────────────────────────────────────────────────────────────────────────────»